Chapter 7. Data Model Specification ‌

Practical Information
1. Revision History
  
  Revision
  Description
  1-15
  Released as revisions of the Dotdot Architecture Model specification
  16
  Initial Release of this specification
2. Scope & Purpose
  This is part of a package of Data Model specifications that are agnostic to underlying layers (encoding, message, network, transport, etc.). Each specification below may be independently maintained. This package, as a whole, shall be independently maintained as agnostic and decoupled from lower layers. This package may be referenced by inclusion in vertical protocol stack specifications.
  Data Model Defines first order elements and namespace for endpoints, clusters, attributes, data types, etc.
  
  Interaction Model Defines interactions, transactions and actions between nodes.
  
  System Model Defines relationships that are managed between endpoints and clusters.
  
  Cluster Library Reference library of cluster specifications.
  
  Device Library Reference library of device type specifications.
3. Origin Story
  The origin of this section is the Dotdot Architecture Model [Dotdot Architecture] and parts of Chapter 2 of the Zigbee Cluster Library specification [ZCL] that define the data model.
  The purpose of this document is to extend and better define the data model architecture for Matter, while not breaking the certifiable cluster specifications in the Zigbee Cluster Library (currently at revision 8). Under the Matter project, new and existing clusters and device types may take advantage of extended architecture elements. Ultimately, the plan is that this architecture is available and maintained for all underlying certifiable protocol stacks.
4. Overview
  This document defines first order elements and namespace of the data model and can also be called the meta-model (of the data model). This document is the "read me first" specification in the data
  model. This data model is ultimately implemented in the application layer of a communication stack.
  This specification does not define how data is stored, encoded or what interactions are allowed on the data.
5. Glossary
  
  Term
  Description
  MS
  Manufacturer or Vendor Specific
  N/A
  not applicable
  desc
  see detailed description section
6. Conventions
  The following conventions are used in Data Model specifications.
  1. Enumerations and Reserved Values
    
    An undefined value or range of an enumeration, field, or identifier SHALL be considered reserved for future revisions of this standard and SHALL NOT be available for implementation. It is RECOMMENDED that a value stay undefined, rather than defining it as "reserved".
    A value or range of an enumeration, field, or identifier that is available for non-standard implementation SHALL be defined as manufacturer specific.
    A value or range of an enumeration, field, or identifier that is available for other parts of this standard SHALL be defined as such.
    A value or range of an enumeration, field, or identifier that is deprecated, and not available for implementation, SHALL be defined as deprecated.
7. Reserved Bit Fields
  - An undefined bit or bit field SHALL be considered reserved for future revisions of this standard and SHALL not be available for implementation.
  - It is RECOMMENDED that a bit stay undefined, rather than defining it as "reserved".
  - An implementation of a revision where a bit is reserved SHALL indicate that bit as zero when conveying that bit in an interaction, and ignore that bit when conveyed from another implementation.
  1. Number Format
    
    In this specification, hexadecimal numbers are prefixed with the designation “0x” and binary numbers are prefixed with the designation “0b”. All other numbers are assumed to be decimal unless indicated otherwise within the associated text.
    Binary numbers are specified as successive groups of 4 bits, separated by a space (“ “) character
    from the most significant bit (next to the 0b prefix and leftmost on the page) to the least significant bit (rightmost on the page), e.g. the binary number 0b0000 1111 represents the decimal number 15.
    Where individual bits are indicated (e.g. bit 3) the bit numbers are relative to the least significant bit which is bit 0.
    
    For example:
    - “0b0000 0xxx” indicates that the lower 3 bits can take any value but the upper 5 bits must each be set to 0.
    - “0x0000 0xxx” indicates that the lower 3 nibbles can take any value but the upper 5 nibbles must each be set to 0.
    When a digit is specified as having any value in the range of that digit, it is specified with an “x” (this should not be confused with the "x" in the prefix "0x" for hexadecimal notation).
Data Qualities
Cluster specifications and device type definitions have tables that define the qualities of elements that make up the cluster or device type. Not all elements have all qualities. For example, a command does not have the read quality. Some elements have intrinsic qualities, that are not listed. For example, an event always has the read quality. Qualities SHALL be defined in columns in tables that describe data model elements.
1. Common Data Table Columns
  The following columns are common across tables describing attributes, commands, events and structs:
  ID
  Defines an identifier for the data model element that is unique at its context.
  
  Name
  Defines a CamelCase name of the element to be used in specification text, not the protocol. Text usage SHALL always be followed with the element name (e.g. CurrentLevel attribute, Stopped event, or Left field).
  Field
  Same as Name. Other headers like "Field", "Bit Field", and "Command Field", are deprecated. Use
  Name.
  
  Conformance
  Defines dependencies on whether an element is optional or mandatory.
  
  Access
  Defines how an element is accessed (e.g. read or write) and what privileges are required to access the data.
2. Other Data Table Columns
  Other columns specific to the element:
  
  Data Type
  A data field requires this column for attribute, event or command data.
  
  Other Qualities
  This is a catchall column for uncategorized qualities.
  
  Default
  This defines a default value for data fields.
  
  Response
  Cluster command tables have this column.
  
  Direction
  Cluster command tables have this column.
  
  Priority
  Event tables have this column.
  
  Value
  Enumerations use this column instead of the ID column.

Conformance

A Conformance column defines optionality and dependency for any data model element or set of elements. This column is valid for attributes, commands, events, enumerations, and fields of commands, events or structures.

Conformance Column	Description
M	This is part of the base mandatory feature set.
O	This is a purely optional element with no dependencies, except the M set.
D	This is a deprecated item that MAY occur in legacy implementations.
X	This is disallowed or obsolete.
EF	True if EF feature or element is supported.
EF=v	True if EF is supported with fixed and non- changing value v.
AB	This SHALL be supported if AB is true. AB is an expression using EF or EF=v terms
[AB]	This MAY be supported if AB is true.

Conformance Column	Description
AB \| CD	This SHALL be supported if either AB or CD is true.
AB & CD	This SHALL be supported if both AB and CD are true.
(AB & CD)	Parentheses can be put around any conformance expression to combine.
[AB & CD]	Optionality may be noted at any level of the logic.
!AB	This SHALL NOT be supported if AB is true.
C.an	C is O (optional), M (mandatory) or any logical AB expression. a is a lower case letter tagging 2 or more attributes or fields. n determines the number of tagged attributes or fields supported to conform to C. n is a number between one ("1") and the number of elements tagged with an a, minus one. n may be suffixed with a plus sign (""), which means the number or more SHALL be supported, otherwise _n_ is exactly the number that SHALL be supported. If _n_ is omitted, then _n_ is considered to be one. Example: "AB.a2" means exactly two "a" elements SHALL be supported. "AB.a2" means at least two of "a" SHALL be supported. "AB.a+" means at least one of "a" SHALL be supported. Note: When this conformance notation is used, all elements using it SHALL have the same notation (example: using "M.a" for one element and "M.a2" for another one is not allowed).

Conformance Tag
A conformance tag for a cluster MAY be the name of a cluster feature (see FeatureMap Attribute). A conformance tag for a cluster MAY be the name of an element in the Name column of the same table. A conformance tag for a device type definition MAY also include a condition of the node.
If multiple conformance tags, such as features "AA" and "BB" are listed as a requirement for a cluster element, then the Conformance column SHALL represent a dependency with OR logic with “AA | BB”, or AND logic using “AA & BB”. If a cluster element is defined for feature "AA", but it is optional for "AA" then the feature is bracketed: "[AA]".
Logical combinations are allowed as well: "[AA] | BB" means optional for AA, but mandatory for BB. "[AA & BB]" means optional only if AA and BB are supported.
Simple dependencies MAY also be defined in the Conformance column. If a Max attribute has a dependency on a Min attribute, then the Conformance column for Max specifies "Min".
If the conformance expression evaluates to false but optional, the expression is false. For example, if AB is false, [AB] evaluates to false and the element is not allowed.
Exclusive logic also applies. If the Absolute attribute is mutually exclusive to the Percentage attribute, then the Conformance column for Absolute would be "!Percentage", and conformance for Percentage would be "!Absolute".
If an element does not have a designated conformance, then it SHALL inherit conformance from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its conformance from the attribute.

Element
An element of the data model is a data construct that supports an instance of data. Listed below are the elements of the data model.
First order elements
fabric, node, endpoint, cluster

Cluster first order elements
command, event, attribute

Nested elements
command field, event field, struct field

Dynamic element
list entry

Semantic elements
device type, data type

Attribute data
elements (above) that are part of an attribute

Data field
attribute, field element, or list entry (see Data Field)
Fabric
A fabric is set of nodes that interact by accessing data model elements as defined in the Interaction Model. A fabric is a security domain that allows a set of nodes to be identified and communicate within the context of the domain. A node is considered to be 'on' a fabric, when it can be identified and interact in the context of that fabric. An interaction is considered to occur 'on' a fabric, when the interaction occurs in the context of that fabric (see Accessing Fabric). Each interaction occurs either on a single fabric, or without a fabric context (see Accessing Fabric).
A node MAY be identified and interact on one or more fabrics.
How a fabric is established and how a node comes to be on a fabric is not defined here and left to the lower layers.
1. Accessing Fabric
  If an interaction is associated with a particular fabric, that fabric is called the "accessing fabric".
  
  If the interaction is not associated with a fabric, the accessing fabric does not exist. In this case any comparison of the accessing fabric to any existing fabric SHALL consider them not equal.
2. Fabric-Index
  Each fabric supported on a node is referenced by fabric-index that is unique on the node. This fabric-index enables the look-up of the full fabric information from the fabric-index. A fabric-index of 0 (zero) or null SHALL indicate that there is no fabric associated with the context in which the fabric-index is being used. If fabric-index is used in a context that is exclusively associated with a fabric, such as fabric-scoped data model elements, then the fabric-index values SHALL NOT include 0 (zero) or null.
  The fabric-index corresponding to the accessing fabric is called the "accessing fabric-index". If the accessing fabric does not exist, the accessing fabric-index SHALL indicate no fabric with a fabric- index of 0.
3. Fabric-Scoped Data
  Most cluster data instances are accessible regardless of the accessing fabric. However, data that is exclusively associated with a particular fabric SHALL be defined as being fabric-scoped. Fabric- scoped data SHALL be defined with the fabric-scoped quality.
  The fabric associated with fabric-scoped data is called the "associated fabric".
  
  Fabric-scoped data allows multiple accessing fabrics to manipulate a list of data items without interfering with each other. See Fabric Filtered List.
  Fabric-scoped data SHALL be limited to the following:
  - list of fabric-scoped structs
  - fabric-sensitive event
  A fabric-scoped data instance is always a composite struct-like data instance, with multiple fields.
  
  Fabric-scoped data SHALL always include the FabricIndex field to indicate the associated fabric. The FabricIndex field for fabric-scoped data SHALL NOT be 0 or null.
  Any interaction, including cluster commands, SHALL NOT cause modification of fabric-scoped data, directly or indirectly, if the interaction has an accessing fabric different than the associated fabric for the data, except in the case of a cluster command that explicitly defines an exception to this rule.
  Data that is fabric-scoped may also be fabric-sensitive, all or in part.
4. Fabric-Scoped IDs
  Some data types are fabric-scoped IDs, including, but not limited to, node ID and group ID.
  
  A fabric-scoped ID MAY require the presence of a fabric-index data type field within the same nesting scope to indicate the fabric associated with the ID in these cases:
  - If the fabric-scoped ID is not part of fabric-scoped data.
  - If the fabric-scoped ID is part of fabric-scoped data with an associated fabric that is not the fabric associated with the ID.
    Fabric-scoped IDs SHALL only be indicated in these elements:
  - structs
  - events
  - commands
  Where necessary, specification text SHOULD define the data to which the fabric-index applies.

Access

Data model elements have access qualities. Some elements have intrinsic access or access limitations. For example: Cluster commands or command fields are not writable.

An Access column defines access to a data model element or set of elements. This column is valid for attributes, commands, events, and nested attribute data fields.

Access Column	Description
R	Read Access
W	Write Access
R[W]	Read Access and optionally Write Access
R*W	Deprecated: use R[W]
Fabric - separate with space from RW
F	Fabric-Scoped Quality
S	Fabric-Sensitive Quality
Privileges - separate with space from RW FS
V	Read Access or Invoke Access requires View privilege
O	Read Access, Write Access, or Invoke Access requires Operate privilege
M	Read Access, Write Access, or Invoke Access requires Manage privilege

Access Column	Description
A	Read Access, Write Access, or Invoke Access requires Administer privilege
Timed - separate with space from RW FS VOMA
T	Write Access or Invoke Access with timed interaction only

Attributes, commands, and events SHALL define their access, and SHALL include privileges in their access definition. For example: An attribute defines whether it is readable or writable, and what privileges are required to do so.

Attributes, commands, and events that do not define any privileges as access qualities SHALL be deemed to have the following:

View privilege required for Read access,
Operate privilege required for Write access,
Operate privilege required for Invoke access for request commands.
No privileges defined for response commands.

For example: An event with implicit read access or explicit 'R' access defaults to access 'R V'. An attribute with access 'RW' defaults to access 'RW VO'. A request command with implicit invoke access defaults to privilege 'O'.
Nested elements MAY define their access, but SHALL NOT include privileges in their access definition. Nested elements SHALL inherit their privileges from the next highest element in the model hierarchy. Nested elements that do not define their access SHALL inherit their access from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its access qualities from attribute.
Elements SHALL only include the lowest required privilege for a type of access. That means:
An event SHALL define the single privilege required for Read access.
A command SHALL define the single privilege required for Invoke access.
A readable attribute SHALL define the single privilege required for Read access.
A writable (but not readable) attribute SHALL define the single privilege (that is not View or ProxyView) required for Write access.
A readable and writable attribute MAY define a single privilege (that is not View or ProxyView) required for both Read and Write access.
A readable and writable attribute MAY define the View or ProxyView privilege as required for Read access and one other privilege (that is not View or ProxyView) as required for Write access.

Read Access
Read access means that a request for data values associated with an element SHALL be supported. This quality SHALL only be defined for cluster event and attribute data definitions. This quality SHALL NOT be defined for cluster command definitions.
This quality is implicitly defined for cluster events and does not need to be stipulated explicitly.
Write Access
Write access means that a request to modify attribute data values SHALL be supported. This quality SHALL only be defined for cluster attribute data definitions. This quality SHALL NOT be defined for cluster event and command definitions.
A cluster specification SHALL define the conditions when write access attribute data is not writable, and SHALL define normative or recommended behavior to follow when this occurs.
An implementation that does not support write access for a field with optional write access SHALL have this declared in its product Declaration of Conformity.
Invoke Access
Invoke access means that a request to execute a command SHALL be supported. This quality SHALL only be defined for cluster command definitions, by defining an appropriate privilege level for the command. This quality SHALL NOT be defined for cluster event and attribute data definitions.
Fabric-Scoped Quality
This defines fabric-scoped data that is scoped to an associated fabric.

This quality acts as an additional constraint over those imposed by the existing Read and Write qualities, namely:
- Fabric-scoped attribute data SHALL NOT be writable unless the accessing fabric is the associated fabric of the data.
- A cluster command SHALL NOT alter fabric-scoped data if the associated fabric is not the accessing fabric.
Fabric-Sensitive Quality
This further restricts access to data that is sensitive to the associated fabric.

This quality acts as an additional constraint over those imposed by the fabric-scoped quality, namely:
- Fabric-sensitive data SHALL NOT be readable unless the accessing fabric is the associated fabric of the data. See fabric-scoped data.
Data that is fabric-sensitive SHALL always be fabric-scoped.
View Privilege
An element with the View privilege SHALL support Read (if readable) and Invoke (if invocable) access if the source of the request is granted the View privilege.
A command with the View privilege defined SHALL NOT alter data that is part of its function (e.g. settings, configuration), but MAY alter data that is internal or diagnostic in nature (e.g. usage statistics).
Operate Privilege
An element with the Operate privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Operate privilege.
Manage Privilege
An element with the Manage privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Manage privilege.
Administer Privilege
An element with the Administer privilege defined SHALL support Read (if readable), Write (if writable), and Invoke (if invocable) access if the source of the request is granted the Administer privilege.
Timed Interaction
A command requires a timed invoke interaction. A writable attribute requires a timed write interaction. This quality requires the use of a timed interaction.
An attempted untimed write interaction to a writable attribute with this quality SHALL generate an error response.
An untimed invoke interaction for a request command with this quality SHALL generate an error response.

Other Qualities

A Quality column defines other qualities not covered in other columns. Some qualities are limited to a specific set of elements. If an element does not have designated qualities, then it SHALL inherit qualities from the next highest element in the model hierarchy. For example: A data field in a struct attribute inherits its access qualities from attribute.

Quality Column	Name	Elements	Description
X	Nullable	data fields	the data type of the data field is nullable

Quality Column	Name	Elements	Description
N	Non-Volatile	attribute data	the attribute data value is non-volatile and is persistent across restarts
F	Fixed	attribute data	the read only value is a fixed value that never changes, unless the program image changes
S	Scene	attribute	the attribute is part of a scene
P	Reportable	attribute	if best effort reporting is supported then the attribute supports a reporting configuration
C	Changes Omitted	attribute data	fast changing data or data where deltas are meaningless to report, and which will not cause delta changes on subscriptions
I	Singleton	device type	the cluster is a singleton on the node for the device type
!Q		device type	the quality Q (from those defined above in this table) is disallowed.

Nullable Quality
See Nullable.
Non-Volatile Quality
See Persistence.
Fixed Quality
Data with this quality is read only and has a fixed value that never changes, unless the program image changes.
Scene Quality
This quality is supported and described in the Scenes cluster.
Reportable Quality
The Subscribe interaction supports all attribute data. This quality is supported by other interactions that only require attribute data with this quality to support interval or change reporting.
Changes Omitted Quality
This quality MAY be given to attribute data that is deemed to have a high rate of change or where changes are not meaningful or too large to convey as part of Subscribe interaction.
Attribute data with this quality SHALL support Read Access, but SHALL NOT have delta changes published as part of a Subscribe interaction.
Singleton
Data with this quality, that be indicated by more than one cluster, represents a single instance of the data, for the node.

Node
A Node encapsulates an addressable, unique resource on the network that has a set of functions and capabilities that a user recognizes distinctly as a functional whole.
This distinction is usually physical, such as the physical device itself, or a logical instance of a physical device.
A node is the highest or outermost first order element in the data model. A node is the outermost unique addressable element of the data model.
A node MAY have multiple node IDs, each ID scoped to a particular fabric. When a node ID is used as the target address of an interaction, the fabric under which the node ID is scoped, is the accessing fabric for the interaction.
The lower layers in a communication stack supporting this data model SHALL support interactions between nodes on a logical inter-network of nodes. Please see the Interaction Model and System Model specifications that describe relationships and interactions between nodes and data model elements on each node.
It is possible for parts of a node to reside on different processors (e.g. separate application and network processors).
A single physical product may support more than one node.
Endpoint
A node is composed of one or more endpoints. An endpoint is an instance of something that could be a service or virtual device as indicated by a device type.
Each endpoint conforms to one or more device type definitions that define the clusters supported on the endpoint. Clusters are object classes that are instantiated on an endpoint.
The word 'device', depending on the context, may be used as shorthand to denote the device type definition as represented by a device type ID, a device type implementation, or an endpoint (device type instance).
There are also many examples in specification text where 'device' is used, when it would be better, and more accurate to use 'node', 'physical device', or 'product'.
The word 'device' may also be used in cluster specifications to describe application software that is supporting an instance of a cluster server or client. In this case, it would be better, and more accurate to use either 'client' or 'server'.
One must be careful to make sure there is no ambiguity when using the word 'device' in specification text, or better yet, use another word.
Cluster
Clusters are the functional building block elements of the data model. A cluster specification defines both a client and server side that correspond with each other through interactions. A cluster may be considered an interface, service, or object class and is the lowest independent functional element in the data model. Each cluster is defined by a cluster specification that defines elements of a cluster including attributes, events, commands, as well as behavior associated with interactions with these elements. Cluster attributes, events, commands and behaviors are mandatory or optional depending on the definition of the cluster. Optional items may have dependencies.
A cluster specification SHALL list one or more Cluster Identifiers. A Cluster Identifier SHALL reference a single cluster specification and SHALL define conformance to that specification. A cluster instance SHALL be indicated and discovered by a Cluster Identifier on an endpoint. A Cluster Identifier also defines the purpose of the instance.
The server cluster supports attribute data, events and cluster commands. The client cluster initiates interactions, including invocation of cluster commands.
1. Cluster Revision
  The revision of a cluster is to enforce backward and forward compatibility, but still allow clusters to be enhanced, fixed, or updated, without changing the cluster’s basic function.
  A cluster revision SHALL be associated with an approved revision and release of a cluster specification. The revision of an instance of a cluster SHALL be represented by the global, mandatory, and read only ClusterRevision attribute. Please see ClusterRevision attribute.
  Changes to a cluster specification SHALL only augment, not modify the primary function of the cluster. Changes to a cluster specification SHALL be represented by incrementing the cluster revision. New revisions of a client cluster SHALL interoperate with older revisions of the server cluster and vice versa. Interoperability between corresponding cluster instances MAY require reading the cluster revision.
  
  For example: If a new product client application supporting revision 3 of cluster X wishes to take advantage of the new behavior that is mandated by revision 3, then the application can read the revision of the corresponding server cluster X in each remote endpoint. If a corresponding cluster X supports revision 3 or greater, then the behavior is supported.
  Examples of changes to a cluster that require incrementing the revision:
  - Changing the behavior of the cluster
  - Changing a read only attribute to become writable
  - Adding new attributes (e.g. min and max of an existing attribute value)
  - Adding new commands, actions, or behavior
  - Adding one or more fields to an existing command
  - Adding a new enumerated value to an attribute
  - Changing anything that is optional to mandatory
  - Changing dependencies of optional items
  - Deprecating parts of the cluster specification
  - Any non-editorial specification text change
2. Cluster Optional Features
  In general, as the number of optional elements in a cluster specification increases, the number of possible combinations increases, which could decrease the interoperability of that cluster.
  Each cluster has a mandatory feature set that consists of mandatory elements such as attributes, commands, fields, values, dependencies, behavior, etc.
  A cluster specification MAY have optional feature sets, each supported by a set of elements (see FeatureMap).
  There is no requirement that each cluster instance supports the same set of optional elements.
  
  If an application knows the ClusterRevision and FeatureMap supported by a cluster instance, then it knows the exact specification text required to be implemented by that instance.
3. Cluster Data Version
  A cluster data version is a metadata increment-only counter value, maintained for each cluster instance. A cluster data version represents an exact & coherent state of cluster attribute data at present. An application may externally hold a data version (called a held data version) published by
  a cluster instance which then represents a cluster instance state at some time in the past. An application may use a held data version to optimize future interactions, by indicating the held data version. A cluster data version is surfaced in the Interaction Model when data is requested. It is used to optimize data read transactions by reducing the need to send the same data. Write interactions may also be qualified with a held data version to disallow changes, unless the cluster instance has the same data version (see Interaction Model). A cluster data version is published as information in some interactions (See Interaction Model). An externally held data version may be included as information in some interactions (See Interaction Model).
  A cluster data version SHALL increment or be set (wrap) to zero if incrementing would exceed its maximum value. A cluster data version SHALL be maintained for each cluster instance. A cluster data version SHALL be initialized randomly when it is first published. A cluster data version SHALL be incremented if any attribute data changes.
4. New Cluster
  When considering the creation of a new cluster specification, it is recommended to consider reusing and extending an existing cluster specification. These are the mechanisms to consider, in order, to extend a cluster:
  1. Optional elements: attribute data, commands, events, enumerations, etc.
  2. Optional feature(s) in the FeatureMap Attribute attribute for a set of elements (see 1)
  3. Cluster Aliasing to reuse a cluster specification as a whole, but with a different semantic
  4. Cluster Inheritance
  5. A new cluster specification
5. Cluster Aliasing
  Cluster aliasing allows the reuse of approved and validated specifications and derived documents, such as test plans, scripts, etc.
  
  For example: A Concentration Measurement cluster specification may be quite abstract but have many mapped Cluster Identifiers each with a more concrete purpose, such as CO2 or O2 concentration measurement.
  - More than one Cluster Identifier, each with unique purpose and semantic content, MAY map to a single cluster specification.
6. Cluster Inheritance
  Cluster inheritance allows the reuse of approved and validated specifications and derived documents, such as test plans, scripts, etc. This allows a new cluster specification to be defined as extending or reducing the requirements of an existing cluster specification, called the base cluster. This also allows an existing cluster specification to be defined as a derived cluster, by creating a new base cluster that is more generic, allowing potential new clusters to be derived from the new base cluster.
  - A derived cluster specification MAY have mandatory requirements that are optional in the base specification.
  - A derived cluster specification MAY remove requirements that are optional in the base specification.
    
    For example: The Bridged Device Basic Information cluster is derived as a reduced form of the base Basic Information cluster, where many informational attributes are not mandatory, because the information is not available from devices behind the bridge. However, the derived cluster provides the same, but reduced, function as the base cluster.
  - A derived cluster specification MAY remove or make optional a requirement that is mandatory in the base specification, if the resulting specification is deemed useful in its reduced form, and logically a subset of the base clusters.
  - It is RECOMMENDED that an extension or reduction for a derived cluster is one or more features or independent elements, not a modification to custom cluster behavior.
  - All new features, elements or behavior introduced by the derived cluster SHALL be defined in the base cluster specification and made optional (in that base cluster specification), to maintain the entire set of requirements and identifier namespace in one place.
  - A derived cluster specification SHALL define its own revision (ClusterRevision attribute) that is independent of the base specification.
  - A base cluster specification MAY be created from an original base cluster, which then becomes a derived cluster to the newly created base cluster.
  If an endpoint supports multiple server clusters that derive or map to the same base cluster specification, then each SHALL represent a single implementation and operate as a single entity or instance. This makes it possible to deploy a new device endpoint with both a base and a derived cluster identifier, which SHALL remain backward compatible to legacy devices that support only the original cluster identifier. Cluster identifiers that are mapped to a single base cluster specification, but are defined for distinctly different purposes, MAY exist together on a device endpoint. If there is no base cluster identifier defined, or no base cluster identifier exists on the same endpoint, then each cluster identifier SHALL represent a separate instance.
  It is a good practice to explore the possibility of either deriving a cluster from an existing cluster or creating a base cluster to map or derive new and existing cluster identifiers. See New Cluster for other options.
7. Status Codes
  A cluster specification defines status code responses to actions depending on the cluster instance state. A status code is either a global Interaction Model status code, or a cluster specific status code that is unique to the cluster specification. A global status code is either scoped to the entire action, or to a cluster request path. A cluster specific status code scoped to a cluster instance is indicated by a cluster path. When an interaction defines a Status Response response, the responder SHALL return a global Interaction Model status code. When an interaction response needs to communicate a cluster specific status code, the responder SHALL return the path to the cluster instance, the
  global status code SUCCESS or FAILURE, and the cluster specific status code. Each cluster specific status code SHALL be associated with either SUCCESS or FAILURE, not both. A cluster specific status code SHALL be, by default, associated with FAILURE unless it is defined as associated with SUCCESS. The global SUCCESS status code means the action was executed for the request path; the global FAILURE status code means that it was not executed.
  - Cluster-specific status code SHALL be defined using the status type.
  - Cluster-specific status codes MAY have the same numeric values as global status codes. Interaction model messages SHALL make it clear whether a particular message field is a global status code or a cluster-specific status code.
  - Cluster-specific status codes SHALL communicate more information than just a generic success or failure condition. Global status codes SHALL be used to communicate such conditions.
  - A server cluster SHALL NOT return a cluster-specific code from another cluster.
8. Cluster Classification
  A cluster SHALL be defined as either a utility cluster or an application cluster.
  1. Utility Cluster
    
    Utility cluster examples scoped to an endpoint: Identify, Descriptor, Binding, Groups, etc. Utility cluster examples scoped to the node: Basic Information, Diagnostics, etc.
    A utility cluster is not part of the primary application operation of an endpoint. It may be used for configuration, discovery, addressing, diagnostics, monitoring device health, software update, etc. It may have a temporary relationship with its cluster counterpart.
  2. Application Cluster
    
    Example application cluster transactions:
    - On/Off cluster - client sends command to server
    - Temperature Measurement cluster - server reports data to client
    An application cluster supports the primary operation of the endpoint. An application cluster supports one or more persistent application interactions between client and server.
    
    An application cluster is not a utility cluster even though it may support utility functions for itself, such as calibration, modes of operation, etc. An application cluster specification SHALL be agnostic about layers and processes outside of its application domain.
    
    Example: A particular temperature measurement cluster may exist on different devices, or in different networks, each with different security & commissioning mechanisms and/or policies.
    Example: A commissioning cluster’s domain is commissioning, but not temperature measurement.

Command

A cluster command is a set of data fields, each of a data type that is conveyed between client and server cluster instances to invoke a behavior on the receiver of the command.

Each command SHALL be listed in a table with data quality columns: ID, Name, Direction, Response, Access, Conformance.

The command table SHALL define the direction of the command as either client to server or server to client. The command table SHALL define the access privileges for each request command or omit the privileges for the default (see default access privileges). The command table SHALL NOT define privileges for a response command. The command table SHALL define a possible response to the command, if any. The command table SHALL define conformance for each command.

A command that is not a response (in the Response column) is a request command. Conformance for a client to server command means the server SHALL recognize and support the client to server command and generate responses as defined. Conformance for a server to client command means the server SHALL send the command as cluster behavior defines, such as in response to a client to server command. Conformance for a command can depend on supported server features. A client SHALL NOT be required to support optional commands or commands depending on an optional feature.

A command description SHALL define when a command is generated. A command description SHALL define the effect upon receipt of a command which may be:

a response command
a success status response
an error status response
no response

*Note

Some legacy clusters have reused the same command ID twice to indicate one command from the client and another from the server. Moving forward, command IDs SHALL NOT be reused in that fashion.

A command definition SHALL clearly define any side-effects on fabric-scoped data, if applicable. A command is identified and indicated with a command ID that SHALL be unique to the cluster*.

A cluster command table SHALL have a Response column with the following values:

Response Column	Description
N	no response is returned for this command
Y	status only is returned for this command
command	name of the response command to this command

A cluster command table SHALL have a Direction column with the following values:

Direction Column	Description
client ⇒ server	command is conveyed from the client to the server cluster
client ⇐ server	command is conveyed from the server to the client cluster

Each command SHALL be described in its own section with a table defining command fields (if any).

Command Fields

A command MAY indicate zero or more fields that are defined in a table. Each command field is defined as a row in the table with these columns:

Column	Description
ID	This is the unique field ID of the field
Name	This is the unique name of the field
Type	This is the data type of the field
Constraint	see Constraint
Quality	see qualities
Default	see Default
Conformance	see Conformance

Command field conformance defines the sender requirements to include the field in a well-formed command for the revision of the cluster. A new command field or a newly made-mandatory command field in a newly revised cluster specification may be omitted by a legacy sender. The cluster specification shall define clear behavior upon receipt of any possible well-formed command with fields that are not present. The cluster specification shall take into consideration the revision history of possible well-formed commands from legacy implementations. To allow deprecation, it is recommended that command fields have a well-defined default value (such as null), and associated default behavior, that is equivalent to omitting the field. Well-defined behavior, for a field that is not present, may be no behavior at all.

For example

A newly revised Noise cluster adds a new mandatory Volume field to the MakeNoise command. Legacy receivers will ignore the Volume field, and legacy senders will not include the field.

Another example

The Volume field is mandatory for the original cluster and there is a proposal to make it optional. The Volume field null value has the semantic of ignoring the field, so instead of making it optional, the default value is used. This would make the receiver logic simpler.

Attribute

An attribute is cluster data. Each attribute SHALL be listed in a table with data quality columns: ID, Name, (Data) Type, Constraint, other Quality, Access, Default (value), and Conformance. An attribute SHALL also define its associated semantics and behavior. Attributes reflect queryable/settable state, configuration and capabilities of a device. If no privileges are explicitly defined for an attribute, then default access privileges take effect. Attribute data MAY also have these other qualities:

Quality	Short	Description
Scene	S	indicates that the data is part of a scene
Persistent	N	indicates that the data value is persistent across restarts
Fixed	F	indicates that the read only data value will never change
Nullable	X	indicates that the data may have a value of null

Fabric-scoped attribute data SHALL be defined as a fabric-scoped list.

Persistence
Persistent data retains its value across a restart. A restart is:
- a program restart or reboot
- power cycle reboot
- user-initiated reboot
- reboot initiated from a program image upgrade
A factory reset is not such a restart. A factory reset is a deliberate behavior to reset persistent data back to its original state when the product left the factory.

For example: a writable attribute that persistently changes the behavior (or mode) of the cluster.
Examples of non-configuration data: device state data, data that is calculated or comes from an external source, such as a sensor value, a time value, etc.
Cluster attributes that represent configuration data SHALL be persistent data unless otherwise specified.

Many clusters define persistent data that is not surfaced as attributes, but is managed by commands. Commissioning or configuration data that is created to allow the cluster to perform its function is persistent data. A group table entry and binding entries are both persistent data across a restart.

For example: After an OTA cluster restart, clusters that have visible state attributes, such as the state of a light, or a window shade SHALL be persistent and define these attributes as persistent.
When a persistent cluster attribute represents controlled state of the device, the device SHALL restore the attribute value to the value before the restart was initiated, and put the device in the state that is represented by the restored value.

Some cluster specifications add a dependency with a persistent configuration attribute A that contains a value to use to restore persistent state attribute B after a restart. This is perfectly valid but cluster specific.
Cluster state data that is not controlled, such as sensor data, is not considered persistent. The cluster specification may put dependencies and limitations on persistent data.

Global Elements

Below is a list of global elements. These are used for self-description of the server.

ID	Name	Element	Type	Constrai nt	Quality	Access	Default	Conform ance
0xFFFD	ClusterR evision	attribute	uint16	1 to max	F	R V		M
0xFFFC	Feature Map	attribute	map32		F	R V	0	M
0xFFFB	Attribute List	attribute	list[attrib- id]		F	R V		M

ID	Name	Element	Type	Constrai nt	Quality	Access	Default	Conform ance
0xFFFA	EventList	attribute	list[event- id]		F	R V		M (provisio nal)
0xFFF9	Accepted Comman dList	attribute	list[comm and-id]		F	R V		M
0xFFF8	Generate dComma ndList	attribute	list[comm and-id]		F	R V		M
0xFE	FabricIn dex	struct or event field	fabric-idx	1 to 254		R V F		fabric- scoped

ClusterRevision Attribute
The ClusterRevision attribute indicates the revision of the server cluster specification supported by the cluster instance. An implementation of a cluster specification before the ClusterRevision attribute was added SHALL have an assumed cluster revision of 0 (zero). For a new cluster specification, the initial value for the ClusterRevision attribute SHALL be 1 (not zero).
A history of revision numbers for a cluster specification release is listed in the Revision History section for a cluster specification. Each new revision of a cluster specification SHALL specify a new revision number incremented (by 1) from the last. The highest revision number in a cluster specification’s Revision History is the revision number for the cluster specification. Therefore, a ClusterRevision attribute value SHALL be the (highest) revision number of the cluster specification that has been implemented.
FeatureMap Attribute
Each instance of a cluster SHALL support this attribute.

The FeatureMap attribute SHALL indicate whether the server supports zero or more optional cluster features. A cluster feature is a set of cluster elements that are mandatory or optional for a defined feature of the cluster. If a cluster feature is supported by the cluster instance, then the corresponding bit SHALL be set to 1, otherwise the bit SHALL be set to 0 (zero). All undefined bits in this attribute SHALL be set to 0 (zero).
The set of cluster elements that are designated as mandatory (M) are implicitly part of the mandatory cluster feature set, and do not have a bit in the FeatureMap attribute.
A cluster specification SHALL support this attribute if the cluster supports features. If a cluster specification is revised to support features (and so this attribute), each bit in the FeatureMap attribute SHALL have a defined default value (1 or 0), to conform with the previous revision of the cluster specification, that did not support the FeatureMap attribute. The value of 1 means the feature elements were mandatory (M) in the previous revision. The value of 0 (zero) means the
elements were optional in the previous revision.

Any newly created feature set of a cluster SHALL be dependent on that cluster.

Feature sets are revision controlled as part of a cluster using the ClusterRevision attribute. The cluster specification is the independent element that is revision controlled. A remote application reading the FeatureMap Attribute and ClusterRevision Attribute will then know exactly what features are supported in the cluster instance.
Each feature set SHALL be well defined within the cluster specification. Each feature SHALL be mapped to a short capitalized code name for the feature set to be referenced as a conformance tag in the cluster specification text, including the Conformance columns defining the elements of the cluster.
If a cluster defines more than 32 feature sets, then it will be necessary to add another feature bitmap attribute. Any client trying to reference the new feature set will know about the new bitmap, because it knows about the new feature set(s). Legacy products will not know about the new feature set nor the new bitmap.
For a cluster whose definition which does not define a FeatureMap, the server SHALL set this attribute to 0 (zero).
AttributeList Attribute
Each instance of a cluster SHALL support this attribute. This attribute SHALL be a list of the attribute IDs of the attributes supported by the cluster instance.
1. AcceptedCommandList
  
  This attribute is a list of client generated commands which are supported by this cluster server instance.
  Each instance of a cluster SHALL support this attribute.
  
  This attribute SHALL be a list of the command IDs for client generated commands that are supported and processed by the server.
  For each client request command in this list that mandates a response from the server, the response command SHALL be indicated in the GeneratedCommandList attribute.
2. GeneratedCommandList
  
  This attribute is a list of server generated commands. A server generated command is a server to client command.
  Each instance of a cluster SHALL support this attribute.
  
  This attribute SHALL be a list of the command IDs for server generated commands.
  
  For each command in this list that is a response to a client command request, the request command SHALL be indicated in the AcceptedCommandList attribute.
EventList Attribute
Each instance of a cluster SHALL support this attribute. For the Matter 1.0 release, support for this attribute is provisional. This attribute SHALL be a list of the event IDs of the events supported by the cluster instance.
FabricIndex Field
This field SHALL be present for fabric-scoped data. This field does not have to be defined explicitly in the field table for fabric-scoped data.
This field SHALL NOT be present in a write interaction. For a write interaction, the server SHALL provide the value of the accessing fabric-index as the FabricIndex field value to processing logic, after receipt of the interaction. For a read interaction this field SHALL be included in all reported data that is defined as fabric-scoped.

Event

An event defines a record of something that occurred in the past. In this regard, an event record can be thought of as a log entry, with an event record stream providing a chronological view of the events on the node.

Unlike attributes, which do not provide any edge-preserving capabilities (i.e. no guarantees that every attribute change will be conveyed to observers), events permit capturing every single edge or change and conveying it reliably to an observer. This is critical for safety and security applications that rely upon such guarantees for correct behavior.

Each cluster event is listed in a table that defines: ID, Priority, Access, Conformance.

Event records are readable, and do not require the read access quality to be explicitly defined.

Priority

Each event record has an associated priority. This priority describes the usage semantics of the event.

The following table defines possible event priorities:

Priority	Description
DEBUG	For engineering debugging/troubleshooting
INFO	Events that either drive customer facing features or provide insights into device functions that are used to drive analytics use- cases
CRITICAL	Events that impact physical safety of users, or ongoing reliable operation of the node function (or cluster of the node)

Event Record
An event record is created by the node at the time the event happens. That record SHALL have the following data fields associated with it that are common to all events:
- Event Number
- Timestamp
- Priority
Each generated event record SHALL have an event priority that MAY override the defined priority for that event.
Each event SHALL be described in a section that defines the purpose of the event and data fields of the event (if any). Event fields SHALL be defined in the form of a struct in a table with the following columns: ID, Name, Type, Constraint, Quality, Default, Conformance.
1. Event Number
  
  This is an event number value that is scoped to the node. This number SHALL be monotonically increasing for the life of the node. This monotonicity guarantee SHALL be preserved across restarts.
  Between restarts, each event record SHALL be assigned a number that is exactly 1 greater than the last created event record on that Node.
  When a node restarts, the event number MAY increase by a larger step than 1. Rationale: Nodes do not need to write every new value of the event number counter to permanent storage each time it is increased (e.g. to prevent flash wear due to many write operations). One example strategy to achieve reduction of non-volatile storage updates is described below:
  1. Read the counter value at start-up.
  2. Before processing any message, write counter + N to storage, where N is a carefully chosen number (e.g. 1000). This number N should be chosen carefully in order not to exhaust the lifetime 64-bit counter space.
  3. Process messages normally until the counter has a value one less than the counter in storage. When this happens, store counter + N to storage.
2. Timestamp
  
  Each event record SHALL have a timestamp at the time it was created (and not when it is reported to a client). This timestamp SHALL either be System Time in Microseconds or Epoch Time Microseconds.
Buffering
Event records SHALL be buffered on the Node, with priority given to events of a higher priority level over a lower priority level. Within a priority level, newer event records SHALL overwrite older event records. The Node SHOULD only overwrite older events if there are newer events created and there is insufficient space to retain both.
Event Filtering
Interactions that report event records MAY be filtered by event ID and/or event number.
Fabric-Sensitive Event
An entire event MAY be defined as having the fabric-sensitive quality; otherwise, it SHALL NOT be associated with a fabric.
A read interaction SHALL NOT filter event records, based on fabric, for event records that are not associated with a fabric.
A read interaction SHALL NOT report fabric-sensitive event records that are associated with a fabric different than the accessing fabric.
A fabric-sensitive event SHALL include the global FabricIndex field. For a fabric-sensitive event it is not required to define the FabricIndex field in the event field table.

Device Type
In this architecture model, a device type is the highest semantic element. A device type defines conformance for a set of one or more endpoints. A device type defines a set of requirements for the node or endpoint in the market.
A device type SHALL define the cluster support for an endpoint. A composed device type MAY define one or more other device types as part of the composed device type.
A device type definition MAY define or use predefined conditions from requirements, limitations and/or capabilities of the node. A device type definition MAY define or use predefined conditions on one or more underlying stack standard(s).
A device type MAY define support of a cluster as dependent upon a condition. A device type definition MAY specify optional clusters that are recommended as enhancements.
A device type definition MAY refine cluster conformance:
- Support of optional cluster elements or features MAY be changed to mandatory depending on device type conditions.
- Support of optional cluster elements or features MAY depend on device type conditions.
A device type definition SHALL specify a device type ID, device revision, and a set of one or more mandatory clusters including each cluster’s minimum revision.

For example: a simple sensor device.
A device type definition MAY be generic and allow many similar clusters, where at least one instance SHALL be required.

If all sensor devices are common in cluster requirements (except the clusters that perform the
sensing), then there is no reason to create a device type for each sensor cluster.

For example: a door lock device or thermostat.
A device type definition MAY be very specific and list particular clusters as mandatory.
1. Device Type Revision
  
  Examples of changes to a device type definition that require incrementing the revision:
  - Mandating a higher revision of one or more mandatory clusters
  - Changing an item from optional to mandatory
  - Deprecating parts of the device type definition
  A device type revision is an unsigned integer that is associated with an approved revision and release of a device type definition. The initial value for a device type revision SHALL be 1. The initial revision (1) of a device type definition SHALL require the latest (at the time of definition the cluster) certifiable revisions of the clusters it mandates. Device type implementations MAY support later revisions of the mandatory clusters as they become certifiable. Any mandatory changes to the device type definition SHALL only augment, not modify, the function of the device. Any changes SHALL increment the version of the device. Newer versions of the device SHALL interoperate with older revisions at the older revision’s level of functionality.
2. Device Type Composition
  A device type definition MAY be a composed device type and therefore require other device types for its composition. A device type instance MAY be composed of other endpoints that support extra cluster instances. Please see the System Model specification for more details.
3. Device Type Classification
  Each device type definition SHALL specify the endpoint as being either a Utility, or Application. Each device type definition SHALL specify the scope as either endpoint or node. Each Application device type definition SHALL specify the endpoint as being either Simple or Dynamic.
  1. Utility Device Type
    
    A Utility device type supports configuration and settings. A utility device type definition SHALL define requirements for utility clusters. A utility device type MAY also represent the physical device or product. There MAY be more than one endpoint supporting a utility device type on a node. Example utility cluster categories: OTA upgrade, diagnostics, basic information. Example utility device type categories: bridge, proxy, power source.
  2. Application Device Type
    
    Application devices types are typically the most common endpoints on a node and in the network.
    An endpoint supporting an application device type is an application endpoint. An Application device type SHALL be scoped to the endpoint. An application endpoint SHALL support clusters the primary application function of the endpoint. Application category examples: HVAC, lighting, home security, etc.
  3. Simple Device Type
    
    A Simple device type supports local control that is persistent, independent, and unsupervised. A Simple device type is an Application device type. Simple devices types are typically the most common endpoints in the network. Simple device type examples: sensors, actuators, lights, on/off switches, on/off power outlets, etc. Simple endpoints support independent operation without central control or gateways. An endpoint supporting a simple device type is a simple endpoint. Simple endpoints SHALL support relationships through bindings.
  4. Dynamic Device Type
    
    A Dynamic device type supports intelligent and supervisory services, such as commissioning, monitoring, trend analysis, scheduling and central management. A dynamic device type is an application device type. An endpoint supporting a dynamic device type is a dynamic endpoint. A dynamic endpoint is typically found on a central controller where there exists an intelligent supervisory application that manages simple device control applications. Typically, a dynamic endpoint supports client clusters for central control, management, monitoring or supervisory functions. Typically, the product supporting a dynamic endpoint has visibility into the entire network (or part thereof) of simple endpoints.
    A dynamic endpoint client cluster instance MAY be used to multiplex transactions to or from multiple simple device server clusters in the network. A dynamic endpoint client cluster MAY initiate interactions to many server clusters in the network. A dynamic endpoint client cluster MAY receive data from many server clusters in the network. Dynamic endpoints MAY support relationships through bindings. A dynamic device endpoint MAY support one or more external agents, outside the node stack, that manage relationships. External agents include, but are not limited to, a cloud application, a smartphone, an in-home display, or a configuration tool.
  5. Device Type Scope
    
    A node device type is a utility device type scoped to a node. A node device type definition SHALL support clusters that represent the entire node. An endpoint supporting a node device type is a node endpoint. A node endpoint MAY also represent the physical device or product. There MAY be more than one node endpoint on a node.
    Other classes of device types are endpoint scoped device types.
4. Extra Clusters on an Endpoint
  An endpoint MAY support later revisions of a cluster mandated by the device type definition. An endpoint MAY support extra clusters not mandated by the device type definition. An endpoint MAY support optional features or cluster items (attributes, commands, events, etc.), that are not mandated by the device type definition. Extra clusters, features, or cluster items, SHALL only augment, not modify, the function of the device type or clusters.
Non-Standard
This architecture model provides mechanisms for non-standard or manufacturer specific items such as clusters, commands, events, attributes and attribute data fields. These items MAY be supported on a certified product. Such vendor specific items SHALL NOT change the standard behavior of the standard items. The specific function of a vendor specific item cannot be tested as part of certification. They can only be tested to verify that they do no harm, and conform to proper behavior with regard to identification, discovery, error processing, etc. A non-standard item SHOULD NOT take the place of a standard item that provides the same function. It is up to the certification authority to make a judgment call that is in keeping with the spirit of these requirements. Implementers are encouraged to develop and certify standard items, not non- standard items.

Data Field

A data field is any attribute, field or entry that is not a collection data type, or data that is not surfaced as an attribute, but defined in a cluster specification.

Optional attribute data MAY be referenced as data fields in other attribute specifications within the same cluster specification. Cluster specifications also define data fields that are not surfaced, such as temporary calculated values, or persistent state values. Any defined data value in a cluster specification is a data field.

Each cluster data field SHALL be defined with a table including these columns for data qualities:

Data Type
Constraint
Quality
Access
Default
Conformance

For example: If an attribute is a struct data type, that is readable and writable, then all fields of the struct are readable and writable.

A data field SHALL inherit (if possible) the qualities from the cluster first-order element of which it is part, unless overridden. It SHOULD be rare to override inherited qualities.

New or optional data fields MAY not be recognized by a receiver, such as a legacy receiver. The data field description SHALL define default behavior (such as absence of behavior) when a new or optional data field is not present. It is recommended to define or use a feature when adding new or optional data fields, to better indicate conformance. It is recommended to define a default value, such as a null value, that indicates such default behavior.

Nullable
When a data field value is required to designate an unknown, invalid, or undefined data value, and there is no obvious data value (e.g. zero), that is within the valid range to indicate this, the data field MAY be designated as nullable, so that an implemented instance of data MAY have the value of null.
In this context, these wordings have the same meaning:
- The data field has the value of null.
- The data field has the null value.
- The data field is the null value.
- The data field is null.
Representation of null for the implementation of the Data Model is a consideration of the underlying encoding specification. The encoding layer SHALL have the capability to indicate null for any nullable data field. How the encoding layer indicates null is outside the scope of the Data Model specification.
All data fields MAY be defined to be nullable, regardless of data type.

A cluster specification SHALL define whether a data field is nullable. A cluster specification SHALL define the meaning of the null value.
Composite data types that have a length (i.e. octet string and list), and derived types that have those as the base type, SHALL NOT differentiate semantically between the null value and the empty (zero length) value. In particular a zero-length value SHALL be allowed for nullable values of these types no matter what other length constraints are imposed on the value, and SHALL have the same semantics as the null value.
Optional or Deprecated
An optional or deprecated data field that is not implemented, and therefore does not exist, SHALL NOT be indicated as the null value. How the encoding layer encodes non-existent data is outside the scope of the Data Model specification.
The Conformance column shall define if a data field is optional or deprecated. To manage the data identifier namespace, a deprecated data field SHALL NOT be removed from text that lists its identifier and default value. The description text of a deprecated data field SHALL be removed for new revisions of specification text.
If the specification text of a cluster depends on the value of an optional or deprecated data field of the same cluster, then the data field SHALL have a well-defined default value that SHALL be used when the data field is not implemented.

Constraint & Value

The tables below describe the nomenclature for describing constraints and default data values. This nomenclature is used in the cluster specifications for data value constraints, defaults, and other definitions.

Common Literal Values

These values are commonly used in cluster text and Default columns in cluster data definition tables.

Value	Description
0	The numeral zero is used to indicate the zero value for analog data. This is equivalent to the boolean value FALSE.
1	This is used for any analog data type to mean that the value is 1. This is equivalent to the boolean value TRUE.
FALSE	"FALSE", "false" or "False" is a boolean value and is equivalent to 0 (zero).
TRUE	"TRUE", "true" or "True" is a boolean value and is equivalent to 1.
NaN	Not a Number defined for any floating point values.
null	This indicates the value of null.
empty	This indicates empty list or string data.
min	The minimum possible data value for the data type.
max	The maximum possible data value for the data type.
numeric units	Some number in some well-defined units as described in the data type (e.g. 100o C)

Constraint

The Constraint column is valid for any attribute or data field of an attribute, event, command or struct. It is RECOMMENDED to always define a constraint for any data field.

Constraint	Description
desc	Defines the constraint is defined in the description section
Numeric Data Type Constraints
x*	Defines a value that is supported.
x to y	Defines a supported value range.
max y	Defines the value range from min to y
min x	Defines the value range from x to max.
all	Defines that all values are supported. Same as: min to max.

Constraint	Description
constraint, constraint…	Defines support of a union of two or more value and value range constraints
Octet String Data Type Constraints
x	Defines the size range in bytes to be exactly x
x to y	Defines the size range in bytes from x to y
min x	Defines that the size limit supported is a minimum of x bytes
max y	Defines the size limit supported is a maximum of x bytes
constraint, constraint…	Defines support of a union of two or more size range or size limit constraints
List Data Type Constraints
x	Defines the range of entries to be exactly x
x to y	Defines the range of entries from x to y
min x	defines the limit supported is a minimum of x entries
max y	Defines the limit supported is a maximum of x entries
constraint, constraint…	Defines support of a union of two or more list range or limit constraints
list_constraint[ entry_constraint ]	Defines list_constraint as a list constraint and entry_constraint as a constraint on the entry data type. See also list entry qualities
Character String Data Type Constraints
char_constraint[ z ]	Defines char_constraint as the string constraint in bytes and z as the maximum number of Unicode codepoints.

* x, y, or z are literal values of the data type or from the Common Literal Values.

List and String Constraint

A comma delimited set of constraints for a list or string defines a union constraint. A union constraint SHALL only have one minimum (min x_) constraint and one maximum (max y) constraint. A union constraint SHALL NOT define a range below the minimum constraint or range greater than the maximum constraint, including the defined minimum (min) and maximum (max) for the data type.
A constraint on a list or string data means that the data SHALL always be indicated within that constraint. A constraint on a writeable list or string data means that the data SHALL support writing within the constraint, and SHALL NOT support writing outside the constraint.
Read Only vs Write Access
Effective Maximum for Character String Data Type

Example: A string with a constraint of "max 128 [32]" dictates that the server provide for a 128 byte string, but the string may contain up to 32 Unicode codepoints
A server SHALL support up to the maximum in char_constraint for a character string data type. The character string data SHALL NOT contain more than z Unicode codepoints.
Nullable in Range

If data is nullable then null SHALL be a valid value.

If the data type is a list or derived from a list, and the list is nullable, then a length of 0 (zero) SHALL be supported, and defined in the constraint column.
If the data type is an octet string, or derived from an octet string (e.g. character string), and the data is nullable, then a length of 0 (zero) SHALL be supported, and defined in the constraint column.

Default Column
A default value defined in the Default column is not meant to be the value used when the server returns to factory fresh settings. Specified conformance for data fields may be optional or change over time. A default value is defined to complete dependencies when the actual data field value is not present.
A data field SHALL have a defined default value when:
- the data field is new, and a default is required for backwards compatibility with legacy instances
- the data field is optional, deprecated, or obsolete and therefore is not always present
- an initial value is needed before the application starts
- the value cannot be determined by the application for the instance
- there is a dependency on the attribute value to formulate other data or affect behavior
  
  If a default value is not defined for a data field, the default value is determined by the following conditions:
- If the data field is nullable then the default value SHALL be null
- Else the default value SHALL be one of the following, depending on type:
  - Boolean: false
  - Analog: 0 or 0.0, depending on range
  - Bitmaps: 0
  - Enumeration: MS
  - Composite:
    - String: empty
    - List: empty
    - Struct: default is recursively composited from the defaults of its member fields
  - Derived types: use the default value of the base type
These are the options for the Default column used for attributes or attribute, command or event data:

Default Column
Description
x
a literal value x of the data type, or as defined in Common Literal Values
MS
a manufacturer or implementation specific value

If the default value of a data field is specified as manufacturer specific, then there SHALL be no defined default value and the application SHALL support a manufacturer specific value that is in the valid range.

Data Types

Each data field in a cluster specification SHALL have a well-defined data type. Each attribute in a cluster specification SHALL map to a single data type.

The table indicates for each data type whether it defines an analog or discrete value. Values of analog types MAY be added to or subtracted from other values of the same type and are typically used to measure the value of physical properties that can vary continuously over a range. Values of discrete data types only have meaning as individual values and SHALL NOT be added or subtracted.

Some data types specify bit-widths for future potential growth in range (analog) or number of values (discrete).

Cluster specifications SHALL use the unique data type short name to reduce the text size of the specification.

Base Data Types

Class	Data Type	Short	ID	Size
Discrete	Boolean
	Boolean	bool	0x10	1 byte
	Bitmap
	8-bit bitmap	map8	0x18	1 byte
	16-bit bitmap	map16	0x19	2 bytes
	32-bit bitmap	map32	0x1B	4 bytes
	64-bit bitmap	map64	0x1F	8 bytes

Class	Data Type	Short	ID	Size
Analog	Unsigned Integer
	Unsigned 8-bit integer	uint8	0x20	1 byte
	Unsigned 16-bit integer	uint16	0x21	2 bytes
	Unsigned 24-bit integer	uint24	0x22	3 bytes
	Unsigned 32-bit integer	uint32	0x23	4 bytes
	Unsigned 40-bit integer	uint40	0x24	5 bytes
	Unsigned 48-bit integer	uint48	0x25	6 bytes
	Unsigned 56-bit integer	uint56	0x26	7 bytes
	Unsigned 64-bit integer	uint64	0x27	8 bytes
	Signed Integer
	Signed 8-bit integer	int8	0x28	1 byte
	Signed 16-bit integer	int16	0x29	2 bytes
	Signed 24-bit integer	int24	0x2A	3 bytes
	Signed 32-bit integer	int32	0x2B	4 bytes
	Signed 40-bit integer	int40	0x2C	5 bytes
	Signed 48-bit integer	int48	0x2D	6 bytes
	Signed 56-bit integer	int56	0x2E	7 bytes
	Signed 64-bit integer	int64	0x2F	8 bytes
Analog	Floating Point
	Single precision	single	0x39	4 bytes
	Double precision	double	0x3A	8 bytes

Class	Data Type	Short	ID	Size
Composite	String
	Octet string	octstr	0x41	desc
	Collection
	List	list	0x48	desc
	Struct	struct	0x4C	desc

Boolean

The Boolean type represents a logical value, either FALSE or TRUE.
- FALSE SHALL be equivalent to the value 0 (zero).
- TRUE SHALL be equivalent to the value 1 (one).

Bitmap (8, 16, 32 and 64-bit)

This data type is typically used to represent simple cluster settings or state that are treated as whole.

The Reserved Bit Fields conventions define reserved bitmap data.

It is RECOMMENDED to define more bits than initially needed to be able to support more values for later revisions.
The Bitmap type MAY be used to support up to 8, 16, 32 or 64 boolean values.
Bits MAY be combined to enumerate other values.
Bits SHOULD be combined as contiguous bit fields.
Future revisions MAY require non-contiguous bit fields.
The conformance for a bit in a bitmap SHALL be mandatory or dependent upon an existing discoverable element, and therefore SHALL NOT be purely optional.
Allowable Conformance for a bit in a bitmap:
Mandatory
Dependent upon a Feature supported in the FeatureMap attribute.
Dependent upon the support of an attribute.

A nullable bitmap SHALL NOT permit use of the most significant bit.

7.18.1.3. Unsigned Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)

This type represents an unsigned integer with length of N bits and a usable range of:
[0..2N-1] if not nullable OR

[0..2N-2] if nullable.

The following table presents the representable values following the above rules:

Width N (bits)	Minimum value	Maximum value if nullable	Maximum value if not nullable
8	0 (0x00)	254 (0xFE)	255 (0xFF)
16	0 (0x0000)	65534 (0xFFFE)	65535 (0xFFFF)
24	0 (0x000000)	16777214 (0xFFFFFE)	16777215 (0xFFFFFF)
32	0 (0x00000000)	4294967294 (0xFFFFFFFE)	4294967295 (0xFFFFFFFF)
40	0 (0x0000000000)	1099511627774 (0xFFFFFFFFFE)	1099511627775 (0xFFFFFFFFFF)
48	0 (0x000000000000)	281474976710654 (0xFFFFFFFFFFFE)	281474976710655 (0xFFFFFFFFFFFF)
56	0 (0x00000000000000)	72057594037927934 (0xFFFFFFFFFFFFFE)	72057594037927935 (0xFFFFFFFFFFFFFF)
64	0 (0x0000000000000000)	18446744073709551614 (0xFFFFFFFFFFFFFFFE)	18446744073709551615 (0xFFFFFFFFFFFFFFFF)

7.18.1.4. Signed Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)

This type represents an signed integer with length of N bits and a usable range of:

[-(2(N-1))..2(N-1)-1] if not nullable OR
[-(2(N-1)-1)..2(N-1)-1] if nullable.

Whether to use two’s complement or another representation for the implementation of the Data Model is a consideration of the underlying encoding specification.

The following table presents the representable values in base-10 following the above rules:

Width N (bits)	Minimum value if nullable	Minimum value if not nullable	Maximum value
8	-127	-128	127
16	-32767	-32768	32767
24	-8388607	-8388608	8388607
32	-2147483647	-2147483648	2147483647

Width N (bits)	Minimum value if nullable	Minimum value if not nullable	Maximum value
40	-549755813887	-549755813888	549755813887
48	-140737488355327	-140737488355328	140737488355327
56	-36028797018963967	-36028797018963968	36028797018963967
64	-9223372036854775807	-9223372036854775808	9223372036854775807

Enumeration (8-bit, 16-bit)

This data type employs scalars to represent context-specific values available from an enumerated set. This data type is nullable.
External standards may be referenced as well as listing the values for the external standard. If the external standard adds values after a specification is adopted, those new values are allowed, but optional. Enumeration values are defined in a table with a Conformance column. When the definition of an enumeration is missing a Conformance column, all values SHALL be considered to have mandatory conformance.
All mandatory readable enumeration values SHALL be understood by the client. All mandatory writable enumeration values SHALL be understood by the server.
If a client indicates an enumeration value to the server, that is not supported by the server, because it is optional, deprecated, or a new value unrecognized by a legacy server, then the server SHALL generate a general constraint error, unless the cluster defines alternate behavior, such as:
- convert the value to a mandatory value
- ignore the value
- generate a cluster specific error
  
  With regard to revising a cluster specification:
- It is RECOMMENDED that a client be as strict as possible by indicating only values that a server supports.
- It is RECOMMENDED that the server be as forgiving as possible when processing unsupported values.
  
  For example: If a server implementation can never enter an enumerated state XYZ, then the value XYZ would never be indicated, therefore the server would not have to support XYZ.
  Note that indicated enumerations MAY comprise only a strict subset of the required enumerations.
Single-Precision

The single precision number format is based on the IEEE 754-2019 single precision (32-bit) format for binary floating-point arithmetic.
See IEEE 754-2019 for more details on the representable values.
Double Precision

The double precision number format is based on the IEEE 754-2019 double precision (64-bit) format for binary floating-point arithmetic.
The format and interpretation of values of this data type follow the same rules as given for the single precision data type, but with wider mantissa and exponent ranges.
See IEEE 754-2019 for more details on the representable values.
Octet String

The octet string data type defines a sequence of octets with a finite octet count from 0 to 65534. It is RECOMMENDED to define a constraint on the maximum possible count.
List

A list is defined as a collection of entries of the same data type, with a finite count from 0 to 65534. A cluster specification may define further constraints on the maximum possible count. The list entry data type SHALL be any defined data type, except a list data type, or any data type derived from a list.
The quality columns for a list definition are for the list.

The list entries are indicated with an index that is an unsigned integer starting at 0 (zero). The maintained order of entries, by index, is defined in the cluster specification, or undefined. Data that is defined as a list is indicated with "list[X]" where X is the entry type. The data type of the list entry has its own qualities, constraints, and conformance.

To define qualities for the list entry data type, make the list entry data type a defined local derived data type, with a table including the columns required to define and constrain the data type.

Name
Type
Constraint
Quality
…
MonthNameStrin g
string
3
F
…
MonthNumber
uint8
1 to 12

…

ID
Name
Type
Constraint
Quality
…
0
Year
int16
-1000 to 3000

…
1
SummerMont hs
list[MonthNu mber]
max 12
N
…

ID
Name
Type
Constraint
Quality
…
0
MonthNames
list[MonthNa meString]
12
N
…
1
SummerYears
list[SummerSt ruct]
max 50

…

For example: Derived data types defined here:
SummerStruct defined here:
Used Here:
For example:
There is an inline shortcut to define the list entry data type constraints. See List Constraints.

ID
Name
Type
Constraint
Quality
…
0
MonthNames
list[string]
12[3]
N
… .

It is RECOMMENDED to put a maximum constraint on the list and list entry data types.

It is RECOMMENDED that a list entry data type be a struct, to enable the addition of new fields to the list’s entries in the future.
- The cluster data version SHALL be incremented when the list order or entries change.
- An entry SHALL NOT be null.
- The list SHALL support reading and reporting all entries.
- The list SHALL support reporting, updates, and/or deletion of one or more entries.
- If the list is writable, it SHALL support writing or deleting the entire list.
- If the list is writable, it SHALL support updating one or more individual entries by indicating an index per updated entry.
- If the list is writable, it SHALL support deleting one or more individual entries by indicating an index per deleted entry.
- If the list is writable, it SHALL support adding one or more individual entries.
- A list MAY define an entry that is a struct that is fabric-scoped (see Fabric-Scoped Quality).
  
  Fabric-Scoped List
- A fabric-scoped list SHALL define an entry data type that is a struct, which SHALL also be fabric-scoped (see Fabric-Scoped Struct).
  Each entry in a fabric-scoped list SHALL be fabric-scoped to a particular fabric or no fabric.
  
  A fabric-scoped list supports a fabric-filter that filters the view of the list for read and write interactions. This filter simplifies client side logic that does not want to read or write fabric data that is not associated with the accessing fabric.
  - An interaction upon a list with fabric-filtering SHALL only indicate and access entries where the associated fabric matches the accessing fabric, and all other entries SHALL be ignored.
  - Fabric-filtered list entries SHALL be in the same order as the full list.
  - Fabric-filtered list entries SHALL be indexed from 0 with no gaps, as if the other entries did not exist.
  - For a write interaction, fabric-filtering SHALL be enabled.
  - When writing to a fabric-scoped list, the write interaction SHALL be on an accessing fabric, otherwise, the write interaction SHALL fail (see Interaction Model).
  - For a read interaction on a list, fabric-filtering MAY be enabled.
  - For a read interaction on a list, with fabric-filtering disabled, the list SHALL be reported as a full list with all entries.
  For example: A fabric-scoped full list with each entry having an associated FabricIndex and Value field:
  
  list = [ { FabricIndex = A, Value = 20 },
  { FabricIndex = B, Value = 30 },
  { FabricIndex = A, Value = 40 },
  { FabricIndex = B, Value = 50 },
  { FabricIndex = B, Value = 60 } ]
  
  would be a fabric-filtered list when accessed with fabric B:
  
  list = [ { FabricIndex = B, Value = 30 },
  { FabricIndex = B, Value = 50 },
  { FabricIndex = B, Value = 60 } ]
  
  Reading a fabric-filtered list entry index 2 accessed with fabric B reports:
  
  list[2] = [ { FabricIndex = B, Value = 60 } ]
  
  Writing fabric-filtered list entry index 1 when accessed with fabric B:
  
  list[1] = [ { FabricIndex = B, Value = 55 } ]
  
  changes the full list to:
  
  list = [ { FabricIndex = A, Value = 20 },
  { FabricIndex = B, Value = 30 },
  { FabricIndex = A, Value = 40 },
  { FabricIndex = B, Value = 55 },
  { FabricIndex = B, Value = 60 } ]
Struct

A struct is a sequence of fields of any data type. Individual fields are identified by a field ID of unsigned integer, starting at 0 (zero), for the first field.
- A struct itself SHALL have no constraint qualities.
- Each struct field SHALL have its own qualities.
- Access, conformance and persistence qualities, when not not explicitly defined, SHALL be inherited from the instance of the struct itself.
- Struct fields MAY have optional conformance.
- A struct SHALL support reading and reporting of all fields.
- A struct SHALL support reporting changes to one or more fields.
- If the struct is writable, it SHALL support writing the entire struct.
- If a field of the struct is writable, the struct SHALL support updating the field.
- Because of optional struct field conformance, instances of the same struct MAY support multiple 'flavors' of the same struct data type, but with a different set of optional fields.
  
  Fabric-Scoped Struct
- A fabric-scoped struct SHALL only be defined and occur as an entry in a fabric-scoped list.
- A fabric-scoped struct SHALL support the global FabricIndex field of type fabric-index, which indicates the associated fabric of the struct, or indicates that there is no associated fabric.
- The table that defines fields of a fabric-scoped struct SHALL NOT list the global FabricIndex field, which is a global field and defined implicitly.
- The global FabricIndex field of a fabric-scoped struct SHOULD NOT be indicated in a write interaction.
- The global FabricIndex field of a fabric-scoped struct SHALL be ignored in a write interaction.
- When a write interaction creates a fabric-scoped struct entry (in a fabric-scoped list), the server SHALL implicitly load the accessing fabric-index into the global FabricIndex field of the struct.
- A fabric-scoped struct MAY be defined with some fields that are fabric-sensitive.
- For interactions on a fabric-scoped struct that report back data, fabric-sensitive struct fields SHALL NOT be indicated when reporting data back to the client, when the struct has an associated fabric, and it is not the accessing fabric.

Derived Data Types

These data types are commonly used and derived from the base data types. If a data type is used by more than one cluster specification, then it SHALL be listed here as a derived data type. Such common data types can then be reused instead of redefined in each cluster specification.

Class	Data Type	Short	Base Type	ID	Size
Analog	Relative
	Percentage units 1%	percent	uint8	0x32	1 bytes
	Percentage units 0.01%	percent100ths	uint16	0x33	2 bytes
	Time
	Time of day	tod	struct	0xE0	4 bytes
	Date	date	struct	0xE1	4 bytes
	Epoch Time in Microseconds	epoch-us	uint64	0xE3	8 bytes
	Epoch Time in Seconds	epoch-s	uint32	0xE2	4 bytes
	UTC Time	utc	same as Epoch Time in Seconds but Deprecated
	System Time in Microseconds	systime-us	uint64	0xE4	8 bytes

Class	Data Type	Short	Base Type	ID	Size
Discrete	Enumeration
	8-bit enumeration	enum8	uint8	0x30	1 byte
	16-bit enumeration	enum16	uint16	0x31	2 bytes
	Priority	priority	enum8	0x34	1 byte
	Status Code	status	enum8	0xE7	2 bytes
	Identifier
	Fabric ID	fabric-id	uint64	0xD1	8 bytes
	Fabric Index	fabric-idx	uint8	0xD2	1 byte
	Node ID	node-id	uint64	0xF0	8 bytes
	IEEE Address	EUI64	same as Node ID but Deprecated
	Group ID	group-id	uint16	0xF1	2 bytes
	Endpoint Number	endpoint-no	uint16	0xE5	2 bytes
	Vendor ID	vendor-id	uint16	0xD3	2 bytes
	Device Type ID	devtype-id	uint32	0xED	4 bytes
	Cluster ID	cluster-id	uint32	0xE8	4 bytes
	Attribute ID	attrib-id	uint32	0xE9	4 bytes
	Field ID	field-id	uint32	0xEF	4 bytes
	Event ID	event-id	uint32	0xEE	4 bytes
	Command ID	command-id	uint32	0xEC	4 bytes
	Action ID	action-id	uint8	0xEA	1 bytes
	Transaction ID	trans-id	uint32	0xEB	4 bytes
	Index
	Entry Index	entry-idx	uint16	0xF2	2 bytes
	Counter
	Data Version	data-ver	uint32	0xD0	4 bytes
	Event Number	event-no	uint64	0xE6	8 bytes

Class	Data Type	Short	Base Type	ID	Size
Composite	String
	Character String	string	octstr	0x42	desc
	Address
	IP Address	ipadr	octstr	0xD3	4 or 16 bytes
	IPv4 Address	ipv4adr	octstr	0xD4	4 bytes
	IPv6 Address	ipv6adr	octstr	0xD5	16 bytes
	IPv6 Prefix	ipv6pre	octstr	0xD6	1 to 17 bytes
	Hardware Address	hwadr	octstr	0xD7	6 or 8 bytes

Time of Day

The Time of Day data type SHALL be a struct with these fields: Hours, Minutes, Seconds, and Hundredths.
The hours field represents hours according to a 24-hour clock. The range is from 0 to 23. The minutes field represents minutes of the current hour. The range is from 0 to 59. The seconds field represents seconds of the current minute. The range is from 0 to 59. The hundredths field represents 100ths of the current second. The range is from 0 to 99. A value of null in any subfield indicates an unused subfield. If all subfields have a value of null, this indicates a null time of day.
Date

The Date data type SHALL be a struct with these fields:

The year - 1900 subfield has a range of 0 to 255, representing years from 1900 to 2155. The month field has a range of 1 to 12, representing January to December. The day of month field has a range of 1 to 31. Note that values in the range 29 to 31 may be invalid, depending on the month and year. The day of week field has a range of 1 to 7, representing Monday to Sunday. A value of null in any subfield indicates an unused subfield. If all subfields have a value of null, this indicates a null date.
Epoch Time in Microseconds

This type represents an offset, in microseconds, from 0 hours, 0 minutes, 0 seconds, on the 1st of January, 2000 UTC (the Epoch), encoded as an unsigned 64-bit scalar value.
This offset is the sum of two parts: time elapsed, not counting leap-seconds, and a local time offset. The local time offset MAY include a timezone offset and a MAY include a DST offset.
Any use of this type SHALL indicate how the associated local time offset is determined in the specific context of that use. This MAY be done, for example, by simply saying the time is a UTC time, in which case the local time offset is 0.
A given Epoch Time value MAY be interpreted in at least two ways:
1. The value can be converted to a local clock date/time (year, month, day, hours, minutes, seconds, microseconds) by treating the local time offset as 0 and finding the UTC (year, month, day, hours, minutes, seconds, microseconds) tuple that corresponds to an elapsed time since the epoch time equal to the given value. The value then represents that tuple, but interpreted in the specific timezone and DST situation associated with the value. This procedure does not require knowing the local time offset of the value.
2. The value can be converted to a UTC time by subtracting the associated local time offset from the Epoch Time value and then treating the resulting value as an elapsed count of microseconds since the epoch time.
  For example, an Epoch Time value of 0x0000_0BF1_B7E1_0000 corresponds to an offset of exactly 152 days. This can be interpreted as "00:00:00 on June 1, 2000" in whatever local time zone is associated with the value. That corresponds to the following times in ISO 8601 notation:
  - 2000-06-01T00:00Z if the associated local time offset is 0 (i.e. the value is in UTC).
  - 2000-05-31T23:00Z if the associated local time offset is +1 hour (e.g. the CET timezone, without daylight savings).
  - 2000-06-01T00:00+02 if the associated local time offset is +1 hour.
  - 2000-06-01T04:00Z if the associated local time offset is -4 hours (e.g. the EDT time zone, which includes daylight savings).
  - 2000-06-01T00:00-04 if the associated local time offset is -4 hours.
    
    Conversion from NTP timestamps
    
    Timestamps from NTP also do not count leap seconds, but have a different epoch. NTP 128-bit timestamps consist of a 64-bit seconds portion (NTP(s)) and a 64-bit fractional seconds portion (NTP(frac)). NTP(s) at 00:00:00 can be calculated from the Modified Julian Day (MJD) as follows:
    NTP(s) = (MJD-15020) * (24*60*60)
    
    where 15020 is the MJD on January 1, 1900 (the NTP epoch)
    
    NTP(s) on January 1, 2000 00:00:00 UTC (MJD = 51544) is 3155673600 (0xBC17C200)
    
    Epoch Time has a microsecond precision, and this precision can be achieved by using the most significant 32 bits of the fractional portion (NTP(frac32)). Conversion between the 128-bit NTP timestamps and a UTC Epoch Time in Microseconds is as follows:
    UTC Epoch Time = (NTP(s) - 0xBC17C200)*10^6 + ((NTP(frac32)*10^6) / 2^32) where all numbers are treated as unsigned 64-bit integers and the division is integer division.
Epoch Time in Seconds

This type has the same semantics as Epoch Time in Microseconds, except that:
- the value encodes an offset in seconds, rather than microseconds;
- the value is encoded as an unsigned 32-bit scalar, rather than 64-bit.
This type is employed where compactness of representation is important and where the resolution of seconds is still satisfactory.
System Time in microseconds

System time in microseconds is an unsigned 64-bit value representing the number of microseconds since boot.
Percentage units 1%

A Percentage is an unsigned 8-bit value representing percent with a resolution of 1%. The range is from 0 (0%) to 100 (100%).
Percentage units 0.01%

A Percentage 100ths is an unsigned 16-bit value representing percent with a resolution of 0.01%. The range is from 0 (0.00%) to 10000 (100.00%).
Fabric-Index

This is an index that maps to a particular fabric on the node, see Fabric-Index. It is used for:
- the accessing fabric index of an interaction
- the FabricIndex global field in fabric-scoped data
Node ID

A 64-bit ID for a node scoped and unique to a particular fabric as indicated by an accompanying fabric-index adjacent instantiation.
Group ID

A 16-bit ID for a group scoped to a particular fabric as indicated by an accompanying fabric index adjacent instantiation.
Endpoint Number

An unsigned number that indicates an instance of a device type.
Vendor ID

A Vendor ID.

Vendor IDs MAY be used as a prefix in a Manufacturer Extensible Identifier format.
Device Type ID

An identifier that indicates conformance to a device type.

Device Type IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Cluster ID

An identifier that indicates conformance to a cluster specification.

Cluster IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Attribute ID

An identifier that indicates an attribute defined in a cluster specification.

Attribute IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Field ID

An identifier that indicates a field defined in a struct.

Field IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Event ID

An identifier that indicates an Event defined in a cluster specification.

Event IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Command ID

An identifier that indicates a command defined in a cluster specification.

Command IDs SHALL be a Manufacturer Extensible Identifier. The specifics of its representation are described in Data Model Types.
Action ID

An identifier that indicates an action as defined in the Interaction Model specification.
Transaction ID

An identifier for a transaction as defined in the Interaction Model specification, see Transaction ID.
Entry Index

This is an index for a list data type.

Status Code

An enumeration value that means a success or error status. A status code is indicated as a response to an action in an interaction (see Interaction Model).

A status code SHALL be one of:

a common status code from the set defined in the Interaction Model status code table.
a cluster status code that is scoped to a particular cluster

The following table defines the the enumeration ranges for status codes.

Status Code Range	Description
0x00	common status code: SUCCESS
0x01	common status code: FAILURE
0x02 to 0x10	cluster scoped status codes
0x70 to 0xCF	other common status codes defined in Interaction Model Status Code Table.

Status codes in an undefined range, or status codes undefined within a range are reserved and SHALL NOT be indicated.

Priority

This is an enumeration of priority used to tag events and possibly other data. The data type does not define any particular ordering among the values. Specific uses of the data type may assign semantics to the values that imply an ordering relationship.

Value	Priority	Description
0	DEBUG	Information for engineering debugging/troubleshooting
1	INFO	Information that either drives customer facing features or provides insights into device functions that are used to drive analytics use-cases
2	CRITICAL	Information or notification that impacts safety, a critical function, or continued operation

Data Version

An unsigned number that indicates a Data Version.
Event Number

An unsigned number that indicates an Event instance.
Character String

The character string data type is derived from an octet string. The octets SHALL be characters with UTF-8 encoding. An instance of this data type SHALL NOT contain truncated code points.
If at least one of the code points within the string has value 31 (0x1F), which is Unicode INFORMATION SEPARATOR 1 and ASCII Unit Separator, then any client making use of the string SHALL only consider the code points that appear before such an INFORMATION SEPARATOR 1 as being the textual information carried by the string. The remainder of the character string after a first INFORMATION SEPARATOR 1 is reserved for future use by this specification.

Note that the character string type is a bounded sequence of characters whose size bound format is not specified in the data model, but rather a property of the underlying encoding. Therefore, no assumptions are to be made about the presence or absence of a length prefix or null-terminator byte, or other implementation considerations.
It is RECOMMENDED to define constraints on the maximum possible string length.
IP Address

Either an IPv4 or an IPv6 address as defined below.
IPv4 Address

The IPv4 address data type is derived from an octet string. The octets SHALL correspond to the four octets in network byte order that comprise an IPv4 address represented utilizing quad-dotted notation.
Examples of encoding:
- Address 192.168.2.235 → C0A802EB
- Address 10.4.200.75 → 0A04C84B
IPv6 Address

The IPv6 address data type is derived from an octet string. The octets SHALL correspond to the full 16 octets that comprise an IPv6 address as defined by RFC 4291. The octets SHALL be presented in network byte order.
Examples of encoding:
- Address 2001:DB8:0:0:8:800:200C:417A → 20010DB80000000000080800200C417A
- Address 2001:0DB8:1122:3344:5566:7788:99AA:BBCC → 20010DB8112233445566778899AABBCC
IPv6 Prefix

The IPv6 prefix data type is derived from an octet string. The octets SHALL be encoded such that:
- The first octet SHALL encode the prefix length, in bits, in the range of 0 to 128.
  - A value of 0 indicates an absent/invalid prefix.
- The subsequent octets SHALL encode the contiguous leftmost bits of the prefix, in network byte order, with left justification, such that the first bit of the prefix is in the most significant bit of the first octet. Encoding SHOULD use the least number of bytes to encode the prefix but MAY include unused trailing zeroes.
  Examples of encoding:
- Preferred minimal encoding: Prefix 2001:0DB8:0:CD30::/60 → 9 octets → 3C20010DB80000CD30
- Preferred minimal encoding: Prefix 2001:0DB8:BB00::/40 → 6 octets → 2820010DB8BB
- Allowed non-minimal encoding: Prefix 2001:0DB8:BB00::/40 → 7 octets → 2820010DB8BB00
Hardware Address

The Hardware Address data type SHALL be either a 48-bit IEEE MAC Address or a 64-bit IEEE MAC Address (e.g. EUI-64). The order of bytes is Big-Endian or display mode, where the first byte in the string is the left most or highest order byte.

Manufacturer Specific Extensions

This section covers Manufacturer Specific (MS) extensions and how they are supported by identifiers, paths, wildcards, discoverability, etc.

Manufacturer Extensible Identifiers
A Manufacturer Extensible Context (MEC) contains a collection of items which MAY be extended by manufacturers. Each item in a MEC has a source which is either Standard, Scoped or a particular Manufacturer Code (MC).
- A Standard source references definitions described in Matter standard clusters.
- A Scoped source adopts the same source as that of the cluster that contains its definition.
- An MC-based source references manufacturer-specific definitions.
Table 63. MEC Example
Context
Source
Items

MEC

Standard
Item 0
Item 1
Item 2

Scoped
Item 0
Item 1
Item 2

MC 1
Item 0
Item 1
Item 2

MC 2
Item 0
Item 1
Item 2

A Manufacturer Extensible Identifier (MEI) identifies an item in an MEC and has no meaning beyond the context of that MEC.

Manufacturer Extensible Identifier (MEI)

An MEI has the following format:

Table 64. MEI Format

Field	Prefix	Suffix
Description	Encodes a source (standard, scoped or a particular MC)	Encodes an item’s key (in context of MEC + source)
Width	16-bit	16-bit
Bit Positions	31..16	15..0

The MEI permits encoding of ~65K keys in the suffix.

A specific MEI MAY only permit certain combinations of the above.

Encoding

The MEI prefix encodes the source Vendor ID and follows the same rules as outlined in Table 1, “Vendor ID Allocations”, with the exception that a Scoped source is encoded using the same prefix as a Standard source. Consequently, a given MEI SHALL NOT permit both Standard and Scoped source types given the ambiguity in telling them apart.
Given the above, the encoding is as follows:

Table 65. MEI Prefix
Prefix
Source
0x0000
Standard OR Scoped
0x0001 - 0xFFF0
Manufacturer Code as per CSA Manufacturer Code Database
0xFFF1 - 0xFFF4
Test Vendor MC

The MEI suffix encodes a key as follows:

Table 66. MEI Suffix

Suffix
Item
0x0000 - 0xFFFE
Item 0 to 65534

Data Model Types

The following data model types SHALL be represented as MEIs:

Table 67. MEI Suffix

Type	Permitted Source Types	Suffix Range
Device Type ID	Standard or MC	0x0000 - 0xBFFF
Cluster ID	Standard or MC	Standard Cluster: 0x0000 - 0x7FFF
Cluster ID	Standard or MC	Manufacturer-Specific Cluster: 0xFC00 - 0xFFFE
Attribute ID (Global)	Standard	0xF000 - 0xFFFE
Attribute ID (Non-Global)	Scoped or MC	0x0000 - 0x4FFF
Event ID	Scoped or MC	0x00 - 0xFF
Command ID	Scoped or MC	0x00 - 0xFF
Field ID (Global)	Standard	0xE0 - 0xFE
Field ID (Non-Global)	Scoped or MC	0x00 - 0xDF
Command ID	Scoped or MC	0x00 - 0xFF

For example:

Table 68. MEI Decoding Example

MEI	Description
0x0000_0000	Standard/Scoped item 0
0x0000_0001	Standard/Scoped item 1
0x0000_0002	Standard/Scoped item 2
0x0000_FFFE	Standard/Scoped item 65534
0x0001_0000	MC 1 item 0

MEI	Description
0x0001_0001	MC 1 item 1
0x0001_0002	MC 1 item 2
0x0001_FFFE	MC 1 item 65534
0x0002_0000	MC 2 item 0
0x0002_0001	MC 2 item 1
0x0002_0002	MC 2 item 2
0x0002_FFFE	MC 2 item 65534
0xFFFF_0000	Invalid

Manufacturer Extensions

A manufacturer extensible context MAY be extended with items from any manufacturer. Such extensions SHALL be identified using an MEI with prefix for that particular manufacturer, and SHALL NOT use a standard/scoped prefix.

There are further constraints:

MS extensions SHALL only be permitted on standard clusters or another existing MS extension of a standard cluster from another manufacturer.
An extended cluster MAY instantiate a struct definition defined in the standard cluster.
A struct that has been extended with new fields SHALL have the same definition in all instances of that struct within a given cluster definition.
A defined element (struct, command, event) SHALL NOT be re-used or instantiable in a different cluster (except in extended clusters)

This is illustrated by the following hypothetical scenario.

Suppose the standard provides cluster ABCD which contains related counters and their recent statistics. The counter values are available as attributes 1 and 2, which are reset daily. The statistics are grouped into a SummarizedStats struct, available as attributes 3 and 4, and track summary statistics for each counter over a recent period (last month). Each instance of the statistics struct has fields 1, 2, and 3, for minimum, maximum, and mean values for that period.

Suppose manufacturer A extends the standard cluster with additional statistics (red below). A adds lifetime counts as attributes 0x000A_0001 and 0x000A_0002, which are never reset. A also adds quartiles Q1, Q2, and Q3 to the standard SummarizedStats struct, as fields 0x000A_0001, 0x000A_0002, and 0x000A_0003. These quartiles are available for all existing instances of the standard struct, such as standard attributes 3 and 4.

Suppose manufacturer B, a partner of manufacturer A, extends the standard cluster further (green below). B wishes to add instances of the standard statistics struct, as attributes 0x000B_0001 and 0x000B_0002, to track summary statistics for each counter, over a different recent period (last year instead of last month). Since manufacturer A had already extended the standard statistics struct, the instantiation of that struct will contain both standard and A’s fields. If B desires to create a new

version of that statistics struct without A’s changes, it would have to declare a new definition of that struct with new fields in it.

Suppose manufacturer C, a partner of manufacturers B and A, adds a MS cluster 0x000C_FC01 (blue below) that doesn’t extend an existing standard cluster. This cluster has a sensor available as attribute 0x0000_0001 of type SensorStats, which has fields 0x0000_0001, 0x0000_0002, and 0x0000_0003, for the sensor’s value, precision, and accuracy. Since Attribute and Field IDs are defined using the 'Scoped' source type, the prefix of '0000' implicitly equates to the same source as the cluster it is defined in, i.e Manufacturer C. C also wishes to add an instance of the SummarizedStats struct as attribute 0x000C_0002, to track summary statistics for the sensor over a recent period (last hour). Since this cluster does not extend any previous cluster, it cannot instantiate any of the extended versions of the SummarizedStats struct as defined previously. Instead, C will have re-define that structure definition within its cluster definition and use it.

Table 69. Hypothetical Standard Cluster

Endpoi nt	Cluster	Attribut e	Attribute Description	Struct Field	Field Description
0x0001	0x0000_A BCD	0x0000_0 001	Counter 1 current value (reset daily)	-	-
		0x0000_0 002	Counter 2 current value (reset daily)	-	-
		0x0000_0 003	Counter 1 (period = month)	0x0000_0 001	Min count
				0x0000_0 002	Max count
				0x0000_0 003	Mean count
		0x0000_0 004	Counter 2 (period = month)	0x0000_0 001	Min count
				0x0000_0 002	Max count
				0x0000_0 003	Mean count

Table 70. Hypothetical Manufacturer A Extension Scenario

Endpoi nt	Cluster	Attribut e	Attribute Description	Struct Field	Field Description
0x0001	0x0000_A BCD	0x0000_0 001	Counter 1 current value (reset daily)	-	-
		0x0000_0 002	Counter 2 current value (reset daily)	-	-
		0x0000_0 003	Counter 1 (period = month)	0x0000_0 001	Min count
				0x0000_0 002	Max count
				0x0000_0 003	Mean count
				0x000A_0 001	Q1 count
				0x000A_0 002	Q2 count
				0x000A_0 003	Q3 count
		0x0000_0 004	Counter 2 (period = month)	0x0000_0 001	Min count
				0x0000_0 002	Max count
				0x0000_0 003	Mean count
				0x000A_0 001	Q1 count
				0x000A_0 002	Q2 count
				0x000A_0 003	Q3 count

Table 71. Hypothetical Manufacturer B Extension of A Scenario

Endpoi nt	Cluster	Attribut e	Attribute Description	Struct Field	Field Description
0x0001


				0x000A_0 002	Q2 count
Endpoi nt	Cluster	Attribut e	Attribute Description
				0xS0t0r0uAc_t0 00F3ield	Q3 coFuinetld Description
		0x000B_0 002	Counter 2 (period = month)	0x0000_0 001	Min count
				0x0000_0 002	Max count
				0x0000_0 003	Mean count
				0x000A_0 001	Q1 count
				0x000A_0 002	Q2 count
				0x000A_0 003	Q3 count

Table 72. Hypothetical Manufacturer C Custom Cluster

Endpoi nt	Cluster	Attribut e	Attribute Description	Struct Field	Field Description
0x0001	`0x000C _FC01 `	0x0000_0 001	Sensor 1 Stats	0x0000_0 001	Value
				0x0000_0 002	Precision
				0x0000_0 003	Accuracy
		0x0000_0 002	Counter 1 (period = hour )	0x0000_0 001	Min daily count
				0x0000_0 002	Max daily count
				0x0000_0 003	Mean daily count

Note the following potential combinations of path components:

Table 73. Hypothetical Manufacturer Extension Path Examples

	Description
0x0001/0x0000_ABCD/0x0000_0003/0x0000_0001	Cluster ID = Standard, Attribute ID = Scoped, Field ID = Scoped: Counter 1 min value
0x0001/0x0000_ABCD/0x0000_0003/0x000A_0001	Cluster ID = Standard, Attribute ID = Scoped, Field ID = MS(A): Counter 1 Q1 daily count over last month
0x0001/0x0000_ABCD/0x000B_0001/0x0000_0001	Cluster ID = Standard, Attribute ID = MS(B), Field ID = Scoped: Counter 1 Q1 daily count over last year

	Description
0x0001/0x0000_ABCD/0x000B_0001/0x000A_0001	Cluster ID = Standard, Attribute ID = MS(B), Field ID = MS(A): Counter 1 Q1 daily count over last year
0x0001/0x000C_FC01/0x0000_0001/0x0000_0002	Cluster ID = MS©, Attribute ID = Scoped, Field ID = Scoped: Sensor 1 precision
0x0001/0x000C_FC01/0x0000_0002/0x0000_0003	Cluster ID = MS©, Attribute ID = Scoped, Field ID = Scoped: Counter 1 (period = hour) Mean
0x0001/0x000C_FC01/0x0000_FFFD	Cluster ID = MS©, Attribute ID = Standard: Cluster revision

Discoverability

The Descriptor Cluster reports the device types and clusters on a node’s endpoints, whether they are standard or from a particular manufacturer.

For example, if a node supports cluster 0x000C_ABCD on endpoints 1 and 2, that information is available in the Descriptor Cluster.

The Read Interaction provides a means to read the contents of all or part of a cluster.

For example, reading cluster 0x0000_ABCD on endpoint 1 might return mandatory attribute

0x0000_0001, optional attribute 0x0000_0009, and MS attributes 0x000A_0001 and 0x000A_0002.

Revision	Description
1-15	Released as revisions of the Dotdot Architecture Model specification
16	Initial Release of this specification

Term	Description
MS	Manufacturer or Vendor Specific
N/A	not applicable
desc	see detailed description section

Default Column	Description
x	a literal value x of the data type, or as defined in Common Literal Values
MS	a manufacturer or implementation specific value

Context	Source	Items
MEC	Standard	Item 0
		Item 1
		Item 2
	Scoped	Item 0
		Item 1
		Item 2
	MC 1	Item 0
		Item 1
		Item 2
	MC 2	Item 0
		Item 1
		Item 2

Prefix	Source
0x0000	Standard OR Scoped
0x0001 - 0xFFF0	Manufacturer Code as per CSA Manufacturer Code Database
0xFFF1 - 0xFFF4	Test Vendor MC

ID	Name	Type	Constraint	Quality	…
0	Year	int16	-1000 to 3000		…
1	SummerMont hs	list[MonthNu mber]	max 12	N	…

ID	Name	Type	Constraint	Quality	…
0	MonthNames	list[MonthNa meString]	12	N	…
1	SummerYears	list[SummerSt ruct]	max 50		…

ID	Name	Type	Constraint	Quality	…
0	MonthNames	list[string]	12[3]	N	… .

Cluster Library Reference library of cluster specifications.

Device Library Reference library of device type specifications.

Enumerations and Reserved Values

Number Format

ID

Name

Field

Name.

Priority

Value

First order elements

Cluster first order elements

Nested elements

Dynamic element

Semantic elements

Attribute data

Data field

Utility Cluster

Application Cluster

*Note

For example

Another example

AcceptedCommandList

GeneratedCommandList

Event Number

Timestamp

Utility Device Type

Application Device Type

Simple Device Type

Dynamic Device Type

Device Type Scope

Common Literal Values

Constraint

List and String Constraint

Read Only vs Write Access

Effective Maximum for Character String Data Type

Nullable in Range

Boolean

Bitmap (8, 16, 32 and 64-bit)

7.18.1.3. Unsigned Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)

7.18.1.4. Signed Integer (8, 16, 24, 32, 40, 48, 56 and 64-bit)

Enumeration (8-bit, 16-bit)

Single-Precision

Double Precision

Octet String

List

Struct

Time of Day

Date

Epoch Time in Microseconds

Epoch Time in Seconds

System Time in microseconds

Percentage units 1%

Percentage units 0.01%

Fabric-Index

Node ID

Group ID

Endpoint Number

Vendor ID

Device Type ID

Cluster ID

Attribute ID

Field ID

Event ID

Command ID

Action ID

Transaction ID

Entry Index

Status Code

Priority